<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>WinGet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>WinGet</h1>

<p>Retrieves the specified window's unique ID, process ID, process name, or a list of its controls. It can also retrieve a list of all windows matching the specified criteria.</p>

<pre class="Syntax">WinGet, OutputVar [, Cmd, WinTitle, WinText, ExcludeTitle, ExcludeText]</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the result of <em>Cmd</em>.</p></dd>

  <dt>Cmd</dt>
  <dd>See list below.
    </dd>

  <dt>WinTitle</dt>
  <dd><p>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</p></dd>

  <dt>WinText</dt>
  <dd><p>If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON.</p></dd>

  <dt>ExcludeTitle</dt>
  <dd><p>Windows whose titles include this value will not be considered.</p></dd>

  <dt>ExcludeText</dt>
  <dd><p>Windows whose text include this value will not be considered.</p></dd>

</dl>

<p><em>Cmd</em> is the operation to perform, which if blank defaults to <em>ID</em>. It can be one of the following words:</p>
<p><strong><a name="ID"></a>ID</strong>: Retrieves the unique ID number (HWND/handle) of a window. If there is no matching window, <em>OutputVar</em> is made blank. The functions <a href="WinExist.htm">WinExist()</a> and <a href="WinActive.htm">WinActive()</a> can also be used to retrieve the ID of a window; for example, <code>WinExist(&quot;A&quot;)</code> is a fast way to get the ID of the active window. To discover the HWND of a control (for use with <a href="PostMessage.htm">Post/SendMessage</a> or <a href="DllCall.htm">DllCall</a>), use <a href="ControlGet.htm#Hwnd">ControlGet Hwnd</a> or <a href="MouseGetPos.htm">MouseGetPos</a>.</p>
<p><strong>IDLast</strong>: Same as above except it retrieves the ID of the last/bottommost window if there is more than one match. If there is only one match, it performs identically to <em>ID</em>. This concept is similar to that used by <a href="WinActivateBottom.htm">WinActivateBottom</a>.</p>
<p><strong>PID</strong>: Retrieves the <a href="Process.htm">Process ID (PID)</a> of a window.</p>
<p id="ProcessName"><strong>ProcessName</strong>: Retrieves the name of the process (e.g. notepad.exe) that owns a window. If there are no matching windows, <em>OutputVar</em> is made blank.</p>
<p id="ProcessPath"><strong>ProcessPath</strong> <span class="ver">[v1.1.01+]</span>: Similar to <em>ProcessName</em>, but retrieves the full path and name of the process instead of just the name.</p>
<p><strong>Count</strong>: Retrieves the number of existing windows that match the specified <em>WinTitle</em>, <em>WinText</em>, <em>ExcludeTitle</em>, and <em>ExcludeText</em> (0 if none). To count all windows on the system, omit all four title/text parameters. Hidden windows are included only if <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p>
<p><strong><a name="List"></a>List</strong>: Retrieves the unique ID numbers of all existing windows that match the specified <em>WinTitle</em>, <em>WinText</em>, <em>ExcludeTitle</em>, and <em>ExcludeText</em> (to retrieve all windows on the entire system, omit all four title/text parameters). Each ID number is stored in a variable whose name begins with <em>OutputVar</em>'s own name (to form a <a href="../misc/Arrays.htm#pseudo">pseudo-array</a>), while <em>OutputVar</em> itself is set to the number of retrieved items (0 if none). For example, if <em>OutputVar</em> is MyArray and two matching windows are discovered, MyArray1 will be set to the ID of the first window, MyArray2 will be set to the ID of the second window, and MyArray itself will be set to the number 2. Windows are retrieved in order from topmost to bottommost (according to how they are stacked on the desktop). Hidden windows are included only if <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on. Within a <a href="../Functions.htm">function</a>, to create a pseudo-array that is global instead of local, <a href="../Functions.htm#Global">declare</a> MyArray as a global variable prior to using this command (the converse is true for <a href="../Functions.htm#AssumeGlobal">assume-global</a> functions).</p>
<p><strong>MinMax</strong>: Retrieves the minimized/maximized state for a window. <em>OuputVar</em> is made blank if no matching window exists; otherwise, it is set to one of the following numbers:<br>
  -1: The window is minimized (<a href="WinRestore.htm">WinRestore</a> can unminimize it). <br>
  1: The window is maximized (<a href="WinRestore.htm">WinRestore</a> can unmaximize it).<br>
  0: The window is neither minimized nor maximized.</p>
<p><strong><a name="ControlList"></a>ControlList</strong>: Retrieves the control names for all controls in a window. If no matching window exists or there are no controls in the window, <em>OutputVar</em> is made blank. Otherwise, each control name consists of its class name followed immediately by its sequence number (ClassNN), as shown by Window Spy.</p>
<p>Each item except the last is terminated by a linefeed (`n). To examine the individual control names one by one, use a <a href="LoopParse.htm">parsing loop</a> as shown in the examples section below.</p>
<p>Controls are sorted according to their Z-order, which is usually the same order as TAB key navigation if the window supports tabbing.</p>
<p>The control currently under the mouse cursor can be retrieved via <a href="MouseGetPos.htm">MouseGetPos</a>.</p>
<p><strong>ControlListHwnd</strong> <span class="ver">[v1.0.43.06+]:</span> Same as above except it retrieves the <a href="ControlGet.htm#Hwnd">window handle (HWND)</a> of each control rather than its ClassNN.</p>
<p><strong>Transparent</strong>: Retrieves the degree of transparency of a window (see <a href="WinSet.htm">WinSet</a> for how to set transparency). <em>OutputVar</em> is made blank if: 1) the OS is older than Windows XP; 2) there are no matching windows; 3) the window has no transparency level; or 4) other conditions (caused by OS behavior) such as the window having been minimized, restored, and/or resized since it was made transparent. Otherwise, a number between 0 and 255 is stored, where 0 indicates an invisible window and 255 indicates an opaque window. For example:</p>
<pre>MouseGetPos,,, MouseWin
WinGet, Transparent, Transparent, ahk_id %MouseWin%  <em>; Transparency of window under the mouse cursor.</em></pre>
<p><strong>TransColor</strong>: Retrieves the color that is marked transparent in a window (see <a href="WinSet.htm#TransColor">WinSet</a> for how to set the TransColor). <em>OutputVar</em> is made blank if: 1) the OS is older than Windows XP; 2) there are no matching windows; 3) the window has no transparent color; or 4) other conditions (caused by OS behavior) such as the window having been minimized, restored, and/or resized since it was made transparent. Otherwise, a six-digit hexadecimal RGB color is stored, e.g. 0x00CC99. For example:</p>
<pre>MouseGetPos,,, MouseWin
WinGet, TransColor, TransColor, ahk_id %MouseWin%  <em>; TransColor of the window under the mouse cursor.</em></pre>
<p><strong>Style</strong> or <strong>ExStyle</strong>: Retrieves an 8-digit hexadecimal number representing style or extended style (respectively) of a window. If there are no matching windows, <em>OutputVar</em> is made blank. The following example determines whether a window has the WS_DISABLED style:</p>
<pre>WinGet, Style, Style, My Window Title
if (Style &amp; 0x8000000)  <em>; 0x8000000 is WS_DISABLED.</em>
  ... the window is disabled, so perform appropriate action.</pre>
<p>The next example determines whether a window has the WS_EX_TOPMOST style (always-on-top):</p>
<pre>WinGet, ExStyle, ExStyle, My Window Title
if (ExStyle &amp; 0x8)  <em>; 0x8 is WS_EX_TOPMOST.</em>
  ... the window is always-on-top, so perform appropriate action.</pre>
<p>See the <a href="../misc/Styles.htm">styles table</a> for a partial listing of styles.</p>
<h3>Remarks</h3>
<p>A window's ID number is valid only during its lifetime. In other words, if an application restarts, all of its windows will get new ID numbers.</p>
<p>ID numbers retrieved by this command are numeric (the prefix &quot;ahk_id&quot; is not included) and are stored in hexadecimal format regardless of the setting of <a href="SetFormat.htm">SetFormat</a>.</p>
<p>The ID of the window under the mouse cursor can be retrieved with <a href="MouseGetPos.htm">MouseGetPos</a>.</p>
<p>Although ID numbers are currently 32-bit unsigned integers, they may become 64-bit in future versions. Therefore, it is unsafe to perform numerical operations such as addition on these values because such operations require that their input strings be parsable as signed rather than unsigned integers.</p>
<p>Window titles and text are case sensitive. Hidden windows are not detected unless <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p>
<h3>Related</h3>
<p><a href="WinGetClass.htm">WinGetClass</a>, <a href="Process.htm">Process</a>, <a href="WinGetTitle.htm">WinGetTitle</a>, <a href="MouseGetPos.htm">MouseGetPos</a>, <a href="ControlGet.htm">ControlGet</a>, <a href="ControlFocus.htm">ControlFocus</a>, <a href="GroupAdd.htm">GroupAdd</a></p>
<h3>Examples</h3>
<pre class="NoIndent"><em>; Example #1: Maximize the active window and report its unique ID:</em>
WinGet, active_id, ID, A
WinMaximize, ahk_id %active_id%
MsgBox, The active window's ID is &quot;%active_id%&quot;.

<em>; Example #2: This will visit all windows on the entire system and display info about each of them:</em>
WinGet, id, list,,, Program Manager
Loop, %id%
{
    this_id := id%A_Index%
    WinActivate, ahk_id %this_id%
    WinGetClass, this_class, ahk_id %this_id%
    WinGetTitle, this_title, ahk_id %this_id%
    MsgBox, 4, , Visiting All Windows`n%a_index% of %id%`nahk_id %this_id%`nahk_class %this_class%`n%this_title%`n`nContinue?
    IfMsgBox, NO, break
}

<em>; Example #3: Extract the individual control names from a ControlList:</em>
WinGet, ActiveControlList, ControlList, A
Loop, Parse, ActiveControlList, `n
{
    MsgBox, 4,, Control #%a_index% is &quot;%A_LoopField%&quot;. Continue?
    IfMsgBox, No
        break
}

<em>; Example #4: Display in real time the active window's control list:</em>
#Persistent
SetTimer, WatchActiveWindow, 200
return
WatchActiveWindow:
WinGet, ControlList, ControlList, A
ToolTip, %ControlList%
return</pre>

</body>
</html>
